<head>
<title>Manual Page</title>
</head>
<body>
<pre>
<a href="cpl_complete_word.html"><b>cpl_complete_word</b></a>              <a href="cpl_complete_word.html"><b>cpl_complete_word</b></a>



</pre><h2>NAME</h2><pre>
       cpl_complete_word,         cfc_file_start,         cfc_literal_escapes,
       cfc_set_check_fn,       cpl_add_completion,       cpl_file_completions,
       cpl_last_error,        cpl_list_completions,        cpl_recall_matches,
       cpl_record_error, del_CplFileConf, del_WordCompletion, new_CplFileConf,
       new_WordCompletion - lookup possible completions for a word

</pre><h2>SYNOPSIS</h2><pre>
       #include &lt;stdio.h&gt;
       #include &lt;libtecla.h&gt;

       WordCompletion *new_WordCompletion(void);

       WordCompletion *del_WordCompletion(WordCompletion *cpl);


       #define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, \
                                         void *data, \
                                         const char *line, \
                                         int word_end)
       typedef CPL_MATCH_FN(CplMatchFn);

       CPL_MATCH_FN(cpl_file_completions);


       CplMatches *cpl_complete_word(WordCompletion *cpl,
                                     const char *line,
                                     int word_end, void *data,
                                     CplMatchFn *match_fn);

       CplMatches *cpl_recall_matches(WordCompletion *cpl);

       int cpl_list_completions(CplMatches *result, FILE *fp,
                                int term_width);

       int cpl_add_completion(WordCompletion *cpl,
                              const char *line, int word_start,
                              int word_end, const char *suffix,
                              const char *type_suffix,
                              const char *cont_suffix);

       void cpl_record_error(WordCompletion *cpl,
                             const char *errmsg);

       const char *cpl_last_error(WordCompletion *cpl);


       #define CPL_CHECK_FN(fn) int (fn)(void *data, \
                                         const char *pathname)

       typedef CPL_CHECK_FN(CplCheckFn);

       CPL_CHECK_FN(cpl_check_exe);

       CplFileConf *new_CplFileConf(void);

       CplFileConf *del_CplFileConf(CplFileConf *cfc);

       void cfc_literal_escapes(CplFileConf *cfc, int literal);

       void cfc_file_start(CplFileConf *cfc, int start_index);

       void cfc_set_check_fn(CplFileConf *cfc, CplCheckFn *chk_fn,
                             void *chk_data);



</pre><h2>DESCRIPTION</h2><pre>
       The  cpl_complete_word() function is part of the tecla library (see the
       <a href="libtecla.html"><b>libtecla</b></a> man page). It  is  usually  called  behind  the
       scenes  by  <a href="gl_get_line.html"><b>gl_get_line</b></a>,  but  can  also be called sepa-
       rately.

       Given an input line containing an incomplete word to be  completed,  it
       calls  a  user-provided callback function (or the provided file-comple-
       tion callback function) to look up all possible completion suffixes for
       that  word.  The  callback function is expected to look backward in the
       line, starting from the specified cursor position, to find the start of
       the  word  to be completed, then to look up all possible completions of
       that word and record them, one at a  time  by  calling  cpl_add_comple-
       tion().


       Descriptions of the functions of this module are as follows:

         WordCompletion *new_WordCompletion(void)

       This  function  creates  the  resources used by the cpl_complete_word()
       function. In particular, it maintains the memory that is used to return
       the results of calling cpl_complete_word().

         WordCompletion *del_WordCompletion(WordCompletion *cpl)

       This  function  deletes  the resources that were returned by a previous
       call to new_WordCompletion(). It always returns  NULL  (ie.  a  deleted
       object). It does nothing if the cpl argument is NULL.

       The  callback  functions  which  lookup  possible completions should be
       defined with the following macro (which is defined in libtecla.h).

         #define CPL_MATCH_FN(fn) int (fn)(WordCompletion *cpl, \
                                           void *data, \
                                           const char *line, \
                                           int word_end)

       Functions of this type are called by cpl_complete_word(),  and  all  of
       the  arguments of the callback are those that were passed to said func-
       tion. In particular, the line argument contains the input line contain-
       ing  the word to be completed, and word_end is the index of the charac-
       ter that follows the last character of the incomplete word within  this
       string.  The  callback  is expected to look backwards from word_end for
       the start of the incomplete word. What constitutes the start of a  word
       clearly  depends on the application, so it makes sense for the callback
       to take on this responsibility. For example, the builtin filename  com-
       pletion  function  looks backwards until it hits an unescaped space, or
       the start of the line.  Having found the start of the word,  the  call-
       back  should  then  lookup  all  possible completions of this word, and
       record each completion via separate calls to  cpl_add_completion().  If
       the  callback  needs access to an application-specific symbol table, it
       can pass it and any other data that it needs, via  the  data  argument.
       This removes any need for globals.

       The callback function should return 0 if no errors occur. On failure it
       should return 1, and register a terse description of the error by call-
       ing cpl_record_error().

         void cpl_record_error(WordCompletion *cpl,
                               const char *errmsg);

       The last error message recorded by calling cpl_record_error(), can sub-
       sequently be queried by calling cpl_last_error(), as described later.

         int cpl_add_completion(WordCompletion *cpl,
                                const char *line, int word_start,
                                int word_end, const char *suffix,
                                const char *type_suffix,
                                const char *cont_suffix);

       The cpl_add_completion() function is called zero or more times  by  the
       completion  callback function to record each possible completion in the
       specified WordCompletion object.  These  completions  are  subsequently
       returned by cpl_complete_word(), as described later. The cpl, line, and
       word_end arguments should be those that were  passed  to  the  callback
       function.  The word_start argument should be the index within the input
       line string of the start of the word  that  is  being  completed.  This
       should  equal  word_end if a zero-length string is being completed. The
       suffix argument is the string that would have to  be  appended  to  the
       incomplete  word  to  complete  it.  If this needs any quoting (eg. the
       addition of backslashes before special charaters) to  be  valid  within
       the displayed input line, this should be included. A copy of the suffix
       string is allocated internally, so there is no need  to  maintain  your
       copy of the string after cpl_add_completion() returns.

       Note  that  in  the  array  of  possible completions which the cpl_com-
       plete_word() function returns, the suffix recorded  by  cpl_add_comple-
       tion()  is listed along with the concatentation of this suffix with the
       word that lies between word_start and word_end in the input line.

       The type_suffix argument specifies an optional string to be appended to
       the  completion  if it is displayed as part of a list of completions by
       cpl_list_completions(). The intention is that this indicate to the user
       the  type of each completion. For example, the file completion function
       places a directory separator after completions that are directories, to
       indicate  their  nature to the user. Similary, if the completion were a
       function, you could indicate this to the user by setting type_suffix to
       "()". Note that the type_suffix string isn't copied, so if the argument
       isn't a literal string between speech marks, be sure  that  the  string
       remains  valid  for  at  least  as  long  as  the  results  of cpl_com-
       plete_word() are needed.

       The cont_suffix is a continuation suffix to  append  to  the  completed
       word  in  the  input line if this is the only completion. This is some-
       thing that isn't part of the completion itself, but that gives the user
       an  indication  about how they might continue to extend the token.  For
       example, the file-completion callback function adds a directory separa-
       tor  if the completed word is a directory. If the completed word were a
       function name, you could similarly aid the user  by  arranging  for  an
       open parenthesis to be appended.

         CplMatches *cpl_complete_word(WordCompletion *cpl,
                                       const char *line,
                                       int word_end, void *data,
                                       CplMatchFn *match_fn);

       The  cpl_complete_word()  is  normally  called  behind  the  scenes  by
       <a href="gl_get_line.html"><b>gl_get_line</b></a>, but can also be called  separately  if  you
       separately  allocate  a WordCompletion object. It performs word comple-
       tion, as described at the beginning of this section. Its first argument
       is  a resource object previously returned by new_WordCompletion().  The
       line argument is the input line string, containing the word to be  com-
       pleted.  The  word_end  argument contains the index of the character in
       the input line, that just follows the last character of the word to  be
       completed.  When  called  by  gl_get_line(), this is the character over
       which the user pressed TAB.  The  match_fn  argument  is  the  function
       pointer of the callback function which will lookup possible completions
       of the word, as described above, and the data argument provides  a  way
       for the application to pass arbitrary data to the callback function.

       If  no errors occur, the cpl_complete_word() function returns a pointer
       to a CplMatches container, as defined below. This  container  is  allo-
       cated as part of the cpl object that was passed to cpl_complete_word(),
       and will thus change on each call which uses the same cpl argument.

         typedef struct {
           char *completion;        /* A matching completion */
                                    /*  string */
           char *suffix;            /* The part of the */
                                    /*  completion string which */
                                    /*  would have to be */
                                    /*  appended to complete the */
                                    /*  original word. */
           const char *type_suffix; /* A suffix to be added when */
                                    /*  listing completions, to */
                                    /*  indicate the type of the */
                                    /*  completion. */
         } CplMatch;

         typedef struct {
           char *suffix;            /* The common initial part */
                                    /*  of all of the completion */
                                    /*  suffixes. */
           const char *cont_suffix; /* Optional continuation */
                                    /*  string to be appended to */
                                    /*  the sole completion when */
                                    /*  nmatch==1. */
           CplMatch *matches;       /* The array of possible */
                                    /*  completion strings, */
                                    /*  sorted into lexical */
                                    /*  order. */
           int nmatch;              /* The number of elements in */
                                    /*  the above matches[] */
                                    /*  array. */
         } CplMatches;

       If an error occurs during completion, cpl_complete_word() returns NULL.
       A   description   of   the   error  can  be  acquired  by  calling  the
       cpl_last_error() function.

         const char *cpl_last_error(WordCompletion *cpl);

       The cpl_last_error() function returns a terse description of the  error
       which  occurred on the last call to cpl_complete_word() or cpl_add_com-
       pletion().

         CplMatches *cpl_recall_matches(WordCompletion *cpl);

       As a convenience, the  return  value  of  the  last  call  to  cpl_com-
       plete_word()   can   be   recalled   at   a   later   time  by  calling
       cpl_recall_matches(). If cpl_complete_word()  returned  NULL,  so  will
       cpl_recall_matches().

         int cpl_list_completions(CplMatches *result, FILE *fp,
                                  int terminal_width);

       When the cpl_complete_word() function returns multiple possible comple-
       tions, the cpl_list_completions() function can be called upon  to  list
       them,  suitably arranged across the available width of the terminal. It
       arranges for the displayed columns of completions to all have the  same
       width,  set  by the longest completion. It also appends the type_suffix
       strings that were recorded with each completion, thus indicating  their
       types to the user.


</pre><h2>THE BUILT-IN FILENAME-COMPLETION CALLBACK</h2><pre>
       By  default the <a href="gl_get_line.html"><b>gl_get_line</b></a> function, passes the follow-
       ing completion callback function to cpl_complete_word(). This  function
       can  also  be  used  separately,  either  by  sending  it  to  cpl_com-
       plete_word(), or by calling it directly from your own completion  call-
       back function.

         CPL_MATCH_FN(cpl_file_completions);

       Certain aspects of the behavior of this callback can be changed via its
       data argument. If you are happy with its default behavior you can  pass
       NULL  in  this argument. Otherwise it should be a pointer to a CplFile-
       Conf object, previously allocated by calling new_CplFileConf().

         CplFileConf *new_CplFileConf(void);

       CplFileConf  objects  encapsulate  the  configuration   parameters   of
       cpl_file_completions().  These parameters, which start out with default
       values, can be changed by  calling  the  accessor  functions  described
       below.

       By default, the cpl_file_completions() callback function searches back-
       wards for the start of the filename being completed,  looking  for  the
       first  un-escaped  space or the start of the input line. If you wish to
       specify a different location, call cfc_file_start() with the  index  at
       which the filename starts in the input line. Passing start_index=-1 re-
       enables the default behavior.

         void cfc_file_start(CplFileConf *cfc, int start_index);

       By default, when cpl_file_completions() looks  at  a  filename  in  the
       input  line,  each  lone  backslash in the input line is interpreted as
       being a special character which removes any special significance of the
       character  which  follows  it, such as a space which should be taken as
       part of the filename rather than delimiting the start of the  filename.
       These  backslashes  are thus ignored while looking for completions, and
       subsequently added before spaces, tabs and literal backslashes  in  the
       list  of  completions.  To have unescaped backslashes treated as normal
       characters, call cfc_literal_escapes() with a  non-zero  value  in  its
       literal argument.

         void cfc_literal_escapes(CplFileConf *cfc, int literal);

       By  default, cpl_file_completions() reports all files who's names start
       with the prefix that is being completed. If you only  want  a  selected
       subset  of  these  files to be reported in the list of completions, you
       can arrange this by providing a callback function which takes the  full
       pathname  of  a file, and returns 0 if the file should be ignored, or 1
       if the file should be included in the list of completions. To  register
       such    a    function   for   use   by   cpl_file_completions(),   call
       cfc_set_check_fn(), and pass it a pointer  to  the  function,  together
       with  a pointer to any data that you would like passed to this callback
       whenever it is called. Your callback can make its  decisions  based  on
       any property of the file, such as the filename itself, whether the file
       is readable, writable or executable, or even based  on  what  the  file
       contains.

         #define CPL_CHECK_FN(fn) int (fn)(void *data, \
                                           const char *pathname)
         typedef CPL_CHECK_FN(CplCheckFn);

         void cfc_set_check_fn(CplFileConf *cfc,
                               CplCheckFn *chk_fn, void *chk_data);

       The  cpl_check_exe() function is a provided callback of the above type,
       for use with cpl_file_completions(). It returns non-zero if  the  file-
       name  that  it is given represents a normal file that the user has exe-
       cute permission to. You could use this to  have  cpl_file_completions()
       only list completions of executable files.

       When  you have finished with a CplFileConf variable, you can pass it to
       the del_CplFileConf() destructor function to reclaim its memory.

         CplFileConf *del_CplFileConf(CplFileConf *cfc);



</pre><h2>THREAD SAFETY</h2><pre>
       In multi-threaded programs, you should use the libtecla_r.a version  of
       the library. This uses POSIX reentrant functions where available (hence
       the _r suffix), and disables features that rely on non-reentrant system
       functions.  In  the  case  of this module, the only disabled feature is
       username completion  in  ~username/  expressions,  in  cpl_file_comple-
       tions().

       Using  the  libtecla_r.a  version of the library, it is safe to use the
       facilities of this module  in  multiple  threads,  provided  that  each
       thread  uses  a  separately  allocated  WordCompletion object. In other
       words, if two threads want to do word completion, they should each call
       new_WordCompletion() to allocate their own completion objects.


</pre><h2>FILES</h2><pre>
       libtecla.a    -    The tecla library
       libtecla.h    -    The tecla header file.


</pre><h2>SEE ALSO</h2><pre>
       <a href="libtecla.html"><b>libtecla</b></a>, <a href="gl_get_line.html"><b>gl_get_line</b></a>, <a href="ef_expand_file.html"><b>ef_expand_file</b></a>,
       <a href="pca_lookup_file.html"><b>pca_lookup_file</b></a>


</pre><h2>AUTHOR</h2><pre>
       Martin Shepherd  (mcs@astro.caltech.edu)



                                              <a href="cpl_complete_word.html"><b>cpl_complete_word</b></a>
</pre>
</body>
